/**
 * Copyright (C) 2012 Foxit Corporation.
 * All Rights Reserved.
 *
 * The following code is copyrighted and contains proprietary information and trade secrets of Foxit Corporation.
 * You can only redistribute files listed below to customers of your application, under a written SDK license agreement with Foxit.
 * You cannot distribute any part of the SDK to general public, even with a SDK license agreement.
 * Without SDK license agreement, you cannot redistribute anything.
 *
 * @file fpdfsignature.h
 * @brief 	Header file for the Signature module.
 * @details	The module offers:
 *			1. Methods for add unsigned signatures on pages.
 *			2. Methods for set the appearance of signatures.
 *			3. Methods for sign and verify signatures with 3rd filters.
 *			4. Methods for remove signatures.
 * @note	If you want to purchase Foxit GSDK license and use ANY of the following functions, please
 *			request for enabling Base Data module explicitly. 
 */
 
 /** 
 * @addtogroup FGSPDFSIGNATURE PDF Signature
 * @brief Definitions and Methods in this module are included in fpdfsignature.h.
 */
 
 /** @{*/

#ifndef __FGSPDFSIGNATURE__
#define __FGSPDFSIGNATURE__

#ifndef __FGSPDFBASE__
    #include "fpdfbase.h"
#endif

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief Get byte range of the source document that to be signed.
 *
 * @param[in] file				The file which prepare to be signed.
 * @param[in] doc			    Reference to a document.
 * @param[in] sigField			Reference to a signature field.
 * @param[out] byteRangeArray	The byte range array which specify the byte range of the source document to be signed.
 * @param[out] sizeofArray		The size of the byte range array.
 *
 * @return ::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFSignatureCalcByteRanges(CFStringRef file, FGSPDFDocumentRef doc, FGSPDFSignatureFieldRef sigField, UInt32 *byteRangeArray, UInt32 *sizeofArray);

/**
 * @brief Save a signed data to the document.
 *
 * @param[in] dstfile			The file name.
 * @param[in] doc				Reference to a document which prepare to be signed.
 * @param[in] sigField			Reference to the signature field.
 * @param[in] signedData    	The byte range array which specify the byte range of the source document to be signed.
 *
 * @return	::kFGSErrorSuccess means get the data successfully.<br>
 *			For more definitions please see definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFSignatureSaveSignedData(CFStringRef dstfile, FGSPDFDocumentRef doc, FGSPDFSignatureFieldRef sigField, CFDataRef signedData);

/**
 * @brief	Get byte range of the source document that has been signed.
 *
 * @param[in] sigField			Reference to the signature field.
 * @param[out] byteRangeArray	The byte range array which specify the byte range of the source document to be signed.
 * @param[out] sizeofArray		The size of the byte range array.
 *
 * @return	::kFGSErrorSuccess means get the data successfully.<br>
 *			For more definitions please see definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFSignatureGetByteRanges(FGSPDFSignatureFieldRef sigField, UInt32 *byteRangeArray, UInt32 *sizeofArray);

/**
 * @brief Add a signature field with a blank appearance at the specified page.
 *	
 * @param[in] doc					Reference to a document.
 * @param[in] page					The page to be placed the signature.
 * @param[in] rect					The rect to be placed the signature. For page system.
 * 
 * @return	Reference to a receive the added signature field handle.
 */
FGSPDFSignatureFieldRef FGSPDFSignatureAdd(FGSPDFDocumentRef doc, FGSPDFPageRef page, CGRect *rect);

/**
 * @brief Initialize the value of a  signature field.
 *	
 * @param[in] doc				Reference to the document.
 * @param[in] sigField			Reference to the signature field.
 * 
 * @return	::kFGSErrorSuccess means get the data successfully.<br>
 *			For more definitions please see definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFSignatureInitFieldValue(FGSPDFDocumentRef doc, FGSPDFSignatureFieldRef sigField);

/**
 * @brief Verify a signature.
 *
 * @param[in] doc				Reference to a document.
 * @param[in] sigField			Reference to a signature to be verified.
 * @param[in] buffer			The signed data buffer.
 *
 * @return ::kFGSErrorSuccess means get the data successfully.<br>
 *			For more definitions please see definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFSignatureCopySignedData(FGSPDFDocumentRef doc, FGSPDFSignatureFieldRef sigField, CFMutableDataRef buffer);

/**
 * @brief Set the signer name.
 * 
 * @param[in] sigField				Reference to a signature field.
 * @param[in] signer				Pointer to the signer name.
 * 
 * @return	::kFGSErrorSuccess means success.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFSignatureSetSigner(FGSPDFSignatureFieldRef sigField, CFStringRef signer);

/**
 * @brief Set the signer distinguished name.
 * 
 * @param[in] sigField				Reference to a signature field.
 * @param[in] dn					Pointer to the distinguished name of signer.
 * 
 * @return	::kFGSErrorSuccess means success.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFSignatureSetDN(FGSPDFSignatureFieldRef sigField, CFStringRef dn);
    
/**
 * @brief Set the signing date.
 * 
 * @param[in] sigField				Reference to a signature field.
 * @param[in] date					Pointer to receive the signing date.
 * 
 * @return	::kFGSErrorSuccess means success.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFSignatureSetDate(FGSPDFSignatureFieldRef sigField, CFStringRef date);
    
/**
 * @brief Set the text to be showed on signature appearance.
 *
 * @param[in] sigField				Reference to a signature field.
 * @param[in] text					Pointer to the appearance text.
 *
 * @return	::kFGSErrorSuccess means success.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFSignatureSetText(FGSPDFSignatureFieldRef sigField, CFStringRef text);
    
/**
 * @brief Set the signing reason.
 * 
 * @param[in] sigField				Reference to a signature field.
 * @param[in] reason				Pointer to signing reason.
 * 
 * @return	::kFGSErrorSuccess means success.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFSignatureSetReason(FGSPDFSignatureFieldRef sigField, CFStringRef reason);
    
/**
 * @brief Set the signing location.
 * 
 * @param[in] sigField				Reference to a signature field.
 * @param[in] location				Pointer to the signing location.
 *
 * @return	::kFGSErrorSuccess means success.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFSignatureSetLocation(FGSPDFSignatureFieldRef sigField, CFStringRef location);

/** 
 * @name FGSPDFSIGNATURE Enumeration Types
 */
/**@{*/
/**
 * @brief Enum Definitions for Signature Show Flag
 */
enum {
    /** @ Show text on signature appearance. */
    kFGSPDFSignatureAPShowText				= 0x100,
    /** @ Show image on signature appearance. */
    kFGSPDFSignatureAPShowImage             = 0x080,
    /** @ Show signer name on description. */
    kFGSPDFSignatureAPShowName				= 0x040,
    /** @ Show location on description. */
    kFGSPDFSignatureAPShowLocation			= 0x020,
    /** @ Show dn on description. */
    kFGSPDFSignatureAPShowDN				= 0x010,
    /** @ Show date on description. */
    kFGSPDFSignatureAPShowDate				= 0x008,
    /** @ Show reason on description. */
    kFGSPDFSignatureAPShowReason			= 0x004,
    /** @ Show label on description. */
    kFGSPDFSignatureAPShowLabel             = 0x002,
    /** @ Show Foxit flag on signature appearance. */
    kFGSPDFSignatureAPShowFoxitFlag         = 0x001,
};
/** @brief Alias of enumeration for signature show flag. */
typedef UInt32 FGSPDFSignatureFlag;
/**@}*/

/**
 * @brief Set the appearance options to optionally show the signature appearance.
 *
 * @param[in] sigField			Reference to a signature field.
 * @param[in] dwFlag			The appearance options. See enum definitions <b>FGSPDFSignatureFlag</b> for more information.
 * 
 * @return	::kFGSErrorSuccess means success.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */ 
FGSErrorRet FGSPDFSignatureSetOption(FGSPDFSignatureFieldRef sigField, FGSPDFSignatureFlag dwFlag);

/**
 * @brief Set the using image data.
 * 
 * @param[in] sigField			Reference to a signature field.
 * @param[in] file              The image file.
 * 
 * @return	::kFGSErrorSuccess means success.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFSignatureSetImageData(FGSPDFSignatureFieldRef sigField, CFStringRef file);

/**
 * @brief Set the filter for the name of the preferred signature handler to use when validating this signature.
 *
 * @param[in] sigField			Reference to a signature field.
 * @param[in] filter			The name of the preferred signature handler to use.
 *
 * @return	::kFGSErrorSuccess means get the data successfully.<br>
 *			For more definitions please see definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFSignatureSetFilter(FGSPDFSignatureFieldRef sigField, CFStringRef filter);

/**
 * @brief A name that describes the encoding of the signature value and key information in the signature dictionary.
 *
 * @param[in] sigField			Reference to a signature field.
 * @param[in] subFilter			A name that describes the encoding of the signature value and key information.
 *
 * @return	::kFGSErrorSuccess means get the data successfully.<br>
 *			For more definitions please see definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFSignatureSetSubFilter(FGSPDFSignatureFieldRef sigField, CFStringRef subFilter);

/**
 * @brief Get the name of the preferred signature handler to use when validating this signature.
 *
 * @param[in] sigField			Reference to a signature field.			
 *
 * @return	The name of the preferred signature handler to use.
 */
CFStringRef FGSPDFSignatureCopyFilter(FGSPDFSignatureFieldRef sigField);

/**
 * @brief Get a name that describes the encoding of the signature value and key information in the signature dictionary.
 *
 * @param[in] sigField			Reference to a signature field.			
 *
 * @return	The name that describes the encoding of the signature value and key information.
 */
CFStringRef FGSPDFSignatureCopySubFilter(FGSPDFSignatureFieldRef sigField);

/**
 * @brief Reset the appearance of the signature field.
 *
 * @param[in] page				Reference to a page.
 * @param[in] sigField			Reference to a signature field.
 *
 * @return	::kFGSErrorSuccess means get the data successfully.<br>
 *			For more definitions please see definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFSignatureResetAppearance(FGSPDFPageRef page, FGSPDFSignatureFieldRef sigField);

/**
 * @brief Count all signatures. 
 *
 * @param[in] doc				Reference to a document.
 * 
 * @return	The count of signatures.
 */
SInt32 FGSPDFSignatureGetCount(FGSPDFDocumentRef doc);
    
/**
 * @brief	Get the specified signature.
 * @param[in] doc				Reference to a document.
 * @param[in] index				The specified index. Start from 0.
 *
 * @return	The specified signature.
 */
FGSPDFSignatureFieldRef	FGSPDFSignatureGet(FGSPDFDocumentRef doc, SInt32 index);

/**
 * @brief Check whether the signature is signed.
 *
 * @param[in] doc				Reference to a document.
 * @param[in] sigField			Reference to a signature.
 * 
 * @return	The flag value whether the signature is signed.
 */
Boolean FGSPDFSignatureIsSigned(FGSPDFDocumentRef doc, FGSPDFSignatureFieldRef sigField);

/**
 * @brief Clear the signed signature data.
 * 
 * @param[in] doc				Reference to a document.
 * @param[in] sigField			Reference to a signature to be cleared.
 * 
 * @return	::kFGSErrorSuccess means success.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 * @note This method can be called to clear the signed signature data, includes its appearance and the signed data
 *		and then leave the blank signature on the page.
 */
FGSErrorRet FGSPDFSignatureClear(FGSPDFDocumentRef doc, FGSPDFSignatureFieldRef sigField);
    
/**
 * @brief Remove an unsigned signature.
 * 
 * @param[in] doc				Reference to a document.
 * @param[in] sigField			Reference to a unsigned signature to be removed.
 *
 * @return	::kFGSErrorSuccess means success.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFSignatureRemove(FGSPDFDocumentRef doc, FGSPDFSignatureFieldRef sigField);
    
/**
 * @brief Delete the signature field handle.
 *
 * @param[in] doc				Reference to a document.
 * @param[in] sigField			Reference to a signature field.
 * 
 * @return	::kFGSErrorSuccess means success.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFSignatureRelease(FGSPDFDocumentRef doc, FGSPDFSignatureFieldRef sigField);


#ifdef __cplusplus
};
#endif

#endif // __FGSPDFSIGNATURE__
/**@}*/

